Documentation on convol

Task: convol
Purpose: Convolve a cube with a "beam function"
Categories: map manipulation, map analysis

Key: map
        The input image. This can be two or three dimensional. No default.

Key: beam
        The input beam. This cannot be 3-dimensional. The beam is generally
        assumed to be symmetrical about its reference pixel, but see the
        "asymmetric" option if this is not so. If this is not given, then
        a gaussian beam must be specified by the fwhm and pa parameters.

Key: fwhm
        This is used to specify the gaussian beam used when convolving.
        Normally it gives the size of the beam to convolve with, but
        using options=final causes CONVOL to interpret the parameters
        as the required resolution of the output image.
        The size, in arcsec, will normally be two numbers, giving the
        full-width at half-maximum of the major and minor axes of the
        gaussian. If only one number is given, the gaussian will have
        equal major and minor axes.
        This parameter is ignored if the "beam" keyword is given.

Key: pa
        The position angle, in degrees, of the gaussian beam.
        Normally this is the position angle of the beam that is used
        when convolving. However options=final causes this parameter to
        be interpreted as the required position angle in the effective
        beam of the output image.
        It is measured north through towards east, in degrees.
        This parameter is ignored if the "beam" keyword is given.

Key: region
        The region of the input map to convolve. See the Users Manual for
        instructions on how to specify this. The default is the entire
        input image.

Key: out
        The output image. No default.

Key: options
        Some extra processing options. Several can be given, separated
        by commas. Minimum match is used.
          "final"    When parameters are given by the FWHM and PA keywords,
                     the "final" option causes CONVOL to interpret these
                     as the resoultion required for the final output image.
          "divide"   Divide, rather than mulitple, the transform of the map
                     by the transform of the beam. That is, perform
                     deconvolution, rather than convolution.
          "asymmetric" Normally the beam is assumed to be symmetric (as it
                     normally is in radio astronomy). This options causes
                     CONVOL to go through the extra steps to handle a possibly
                     asymmetric beam. If the beam is asymmetric, and you go
                     not give this option, CONVOL symmetrises the beam (i.e.
                     discards the anti-symmetric component).
          "correlate" Correlate rather than convolve with the beam. The
                     difference between correlation and convolution are only
                     apparent for asymmetric beams.

Key: scale
        The scale factor to multiply the output by. The default is for
        CONVOL to determine the appropriate scale factor to make the
        output in JY/BEAM.
        NOTE: If the input image is in units of JY/BEAM, then to determine
        the appropriate scale factor, CONVOL must know the beam parameters
        (bmaj, bmin and bpa items) of both the input map and the beam. If
        these items are not present, CONVOL issues a warning and uses a scale
        factor of 1.

Key: sigma
        When doing devonvolution (options=divide), this gives a noise
        parameter. Default is 0.